home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / PowerPlant / HMarqueeCaption 1.1 / HMarqueeCaption README next >
Encoding:
Text File  |  1997-07-15  |  9.7 KB  |  244 lines  |  [TEXT/CWIE]
  1. /*******************************************************************************\
  2. |                                                                                |
  3. |    HMarqueeCaption ©1997 John C. Daub. All rights reserved.                    |
  4. |                                                                                |
  5. |    John C. Daub <mailto:hsoi@eden.com>                                            |
  6. |    <http://www.eden.com/~hsoi/>  <http://www.eden.com/~hsoi/prog.html>            |
  7. |                                                                                |
  8. \*******************************************************************************/
  9.  
  10.  
  11. DESCRIPTION
  12. ```````````
  13.  
  14. A Metrowerks PowerPlant™ inherited class that displays a horizontally scrolling
  15. (from right to left) "marquee" of text, similar in appearance to the scrolling
  16. JavaScript marquee that you often see across the bottom of web browser windows.
  17.  
  18. Features:
  19.  
  20. - Utilizes offscreen GWorlds for smooth scrolling of text.
  21.  
  22. - Uses text Handles for an amount of text limited only by available memory.
  23.  
  24. - Utilizes modifier keys to modify scrolling behavior (increase scrolling
  25.   speed, scroll left to right, pause scrolling).
  26.  
  27. Can be used in About boxes for scrolling credits, in JavaScript implementations
  28. for the scrolling caption, in applications that need ticker-tape-style
  29. animations, or anywhere a marquee-style sign and animation is desired.
  30.  
  31. The HMarqueeCaption distribution contains the HMarqueeCaption class, a CTYP
  32. resource for easier editing in Metrowerks Constructor™, and a demonstration
  33. application to show just how easy it is to use HMarqueeCaption (made with
  34. CodeWarrior Professional 1).
  35.  
  36.  
  37. USAGE
  38. `````
  39.  
  40. Implementing an HMarqueeCaption in your PowerPlant-based project is very
  41. simple.
  42.  
  43. Place the "HMarqueeCaption.CTYP" file in the "Custom Types" folder within
  44. the "Metrowerks PowerPlant" folder (this folder is only available in CW Pro1
  45. and greater. If you are working with a CodeWarrior prior to Pro1, just
  46. place the file in the same folder as the Constructor™ application).
  47.  
  48. Launch Constructor™ and edit as usual. HMarqueeCaption should be available
  49. in the Catalog window for easy drag and drop editing.
  50.  
  51. TEXT ID            -    the ResIDT of the 'TEXT' resource containing the text for
  52.                     the marquee.
  53.  
  54. Text Traits ID    -    the ResIDT of the 'Txtr' resource for the text
  55.  
  56. Delay            -    the amount of time (in ticks) to wait before scrolling.
  57.                     This helps to prevent the text from scrolling too fast
  58.                     (e.g. on a very high-end PowerMac).
  59.  
  60. Scroll Amount    -    the amount (in pixels) to scroll each time through the loop
  61.  
  62. Reset on Resize    -    when the pane (or it's superView) is resized, reset the
  63.                     caption to the beginning, or just continue from where you
  64.                     were.
  65.  
  66. As general recommendations, I prefer to set Delay to 1, Scroll Amount to 1,
  67. and the frame bindings (if relevant) to bind to left and right. Those are my
  68. only recommendations... everything else is up to you.
  69.  
  70. As you enter your 'TEXT', you do not need to worry about the 'styl' resource
  71. as this information is discarded -- a 'Txtr' is used instead. Additionally,
  72. any carriage returns and/or line feeds are stripped from the text before it
  73. is displayed (they just don't show up very well on screen) and replaced with
  74. spaces. Keep this in mind when "laying out" your 'TEXT' resource.
  75.  
  76. Then be sure to add the HMarqueeCaption.cp to your project, register the
  77. class (use the RegisterClass_() macro), and off you go!
  78.  
  79. During runtime, the speed of the scrolling is not only affected by the
  80. settings you've given it, but also some factors within and outside of
  81. your control.
  82.  
  83. First, HMarqueeCaption is an LPeriodical repeater so the behavior is dependant
  84. upon the event loop. If some other application is hogging the processor,
  85. scrolling my be slowed greatly. The joys of cooperative multitasking.
  86.  
  87. Second, the use of GWorlds, the size of the caption, etc. can affect the
  88. speed of the drawing. So do try to test (if possible) on lower-end machines
  89. to ensure performance is still adequate for your needs.
  90.  
  91. Third, the modifier keys can affect the scrolling:
  92.  
  93. command key    -    Ignores the delay amount and draws as often as SpendTime is called.
  94.                 Can improve scrolling time, especially on faster computers. Also
  95.                 gives the best scrolling in terms of cosmetics
  96.  
  97. option key    -    Scroll one more pixel than usual. Again speeds scrolling but can
  98.                 make scrolling a bit choppy. Option and Command together REALLY
  99.                 speed things up.
  100.  
  101. shift key    -    Scroll backwards (right to left).
  102.  
  103. control key    -    Stop scrolling (pause)
  104.  
  105. And all the keys can be used in combination: command-opt-shift will scroll very
  106. quickly from right to left.
  107.  
  108.  
  109. CREDITS
  110. ```````
  111.  
  112. Thanx to Michele and Wade (my wife and my son) for letting me spend too much
  113. time on the computer to write things like this. :-)
  114.  
  115.  
  116. DISCLAIMER
  117. ``````````
  118.  
  119. This is NOT a product of Metrowerks Corporation.  Please do NOT contact Metrowerks
  120. for help/support of this class/code.  If you need support, please use the contact
  121. information given below.
  122.  
  123.  
  124. LICENSING AND USAGE AGREEMENT
  125. `````````````````````````````
  126.  
  127. John C. Daub (author) grants you, and you accept, a nonexclusive, nontransferable
  128. license to distribute this code for you within your programs and projects.  You may
  129. distribute this code in object code form only and only on magnetic diskettes,
  130. CD-ROM, or other media with your programs into which this code has been
  131. incorporated (if you need to distribute your program by some other medium, please
  132. contact the author).  You agree that this license gives you no title nor rights
  133. of ownership in, of, and/or to this code, and acknowledge that this code
  134. is property of John C. Daub.  This code is NOT in the public domain.
  135.  
  136. Permission is granted to the following organizations to distribute this
  137. code on their CD-ROM collections:
  138.  
  139. Pacific HiTech, Inc            - Info-Mac CD-ROM
  140. Celestin Company            - Apprentice CD
  141. Meterowerks Corporation        - CodeWarrior
  142.  
  143. If you and/or your organization wishes to distribute this code and are
  144. not explicitly listed above, please contact John C. Daub.
  145.  
  146. You may modify the source code, compile it, and incorporate the resulting object
  147. code into your programs.  If you modify the code, you cannot redistribute the
  148. modified code under the same class/code name.  Furthermore, to prevent any
  149. problems and/or infringements, please contact the author prior to redistribution
  150. of any modified code.
  151.  
  152. John C. Daub licenses this code to you on an "AS IS" basis.  John C. Daub makes
  153. no warranties, neither expressed nor implied, regarding this code, its
  154. merchantability, nor its fitness for any purpose.  John C. Daub agrees to make a
  155. reasonable effort to provide written or verbal corrections for any problems
  156. that might be found in this code.
  157.  
  158. Use of this code must be credited in an appropriate manner and location (such
  159. as printed or online documentation and/or About boxes) with the following
  160. credit line:
  161.  
  162.      HMarqueeCaption ©1997 John C. Daub.  All rights reserved.
  163.  
  164. If this license is too restrictive with the current law in your state or country,
  165. you should not use this code at all. Furthermore, if you personally find this
  166. agreement too restrictive or not to your satisfaction, you should not use this
  167. code at all.
  168.  
  169.  
  170. FUTURE
  171. ``````
  172.  
  173. -    It might be nice to optionally have the "entry" and "exit" of the caption
  174.     fade in and out, similar to how the scrolling credits work in the CW IDE's
  175.     About box.
  176.  
  177. -    A way to try to get around the event-loop dependacy on the scrolling speed.
  178.     A lot of this is just something you have to live with due to the cooperative
  179.     multitasking nature of the MacOS... but there could be things that could
  180.     be done to try to get around it. Of course, would it be worth it? Perhaps
  181.     investigate threads?
  182.  
  183. -    See if it might be possible that when the text wraps from beginning to end
  184.     that there isn't such a large gap... i.e. try to have the ends "touch"
  185.     each other (or be seperated by a set amount of space).
  186.  
  187. -    Multistyle?
  188.  
  189. -    Allow text to either scroll right to left or left to right, whatever the
  190.     programmer wants.
  191.  
  192.  
  193. CONTACT INFORMATION
  194. ```````````````````
  195.  
  196. Even though you don't need to send me email or register or anything to
  197. use the code, it would still be nice to drop me a line and let me know
  198. what you think.  If you find any bugs or add any cool features, send them
  199. to me so I can add it to the official distribution. Furthermore, if I
  200. have your contact information, I can notify you when new versions are
  201. released -- can be very handy if say there is a fatal crashing bug
  202. in the code or some such. So, it's probably in your own best interest
  203. to drop me a line :-)
  204.  
  205. Also, be sure to visit my web site
  206.  
  207. <http://www.eden.com/~hsoi/prog.html>
  208.  
  209. and "register". I won't know if you're "registered" or not, but it's a nice
  210. way that you can be notified of product updates (e.g. I make a new
  211. version, post it on that page, if you're registered, you'll be emailed
  212. automatically that the page changed).
  213.  
  214. John C. Daub
  215. <mailto:hsoi@eden.com>
  216. <http://www.eden.com/~hsoi/prog.html>
  217.  
  218.  
  219. CHANGE HISTORY
  220. ``````````````
  221.  
  222. Date        Vers    Who        Notes
  223. ----------------------------------------------------------------------------
  224. 26 Jun 97    1.0        JCD        - Initial release.
  225.  
  226. 13 Jul 97    1.1        JCD        - All ctor's use initialization lists instead of
  227.                             assignment (where possible).
  228.                             - All member data is now private (was protected). Appropriate
  229.                             accessor functions have been created (as public or
  230.                             protected, depending on context). Helps to further abstract
  231.                             the user away from the data (good C++ style).
  232.                             - Added include for PowerPlant_PCH to be consistant with
  233.                             PowerPlant sources.
  234.                             - Inline functions no longer defined within class declaration.
  235.                             Definitions moved outside of the class, but still in the header
  236.                             file. (Only affected SetTextTraitsID). #pragma mark's
  237.                             added to source file to ease navigation and user indexing.
  238.                             - All member data is now initialized properly to some
  239.                             default value (prior, some data was never properly
  240.                             initialized).
  241.                             - GetTextID now inline (in accordance with the above
  242.                             changes)
  243.                             - DisposeGWorld renamed to DestroyGWorld so as to prevent
  244.                             any conflicts with the Toolbox's DisposeGWorld.